Amiga Plus 2002 #11/Amiga Plus CD - 2002 - No. 11.iso/Tools/AmigaSystem/AmiStart/ToolsSDK.lha/developer.doc

Text File | 2002-06-15 | 15.7 KB | 347 lines

Amistart Tool creating Developer Documentation:

First of all:
    excuse the very bad description, it was fast made and my english is very bad

This documentation describes how to implement AmiStart Tools, the
AmiStart Tools developer Kit is based on the "Lib37x" available on AMINET done by
Andreas R. Kleinert. This means you could spread Tool-libraries but you can't
spread the sourcecode of them without asking Andreas R. Kleinert for permission


What are Tools?

Tools have a library equal structure, all Tools with the same Version must
implement all Functions for this Version.

Tools are information servers added to the right border on the TaskBar, for example
Memory usage meters, cpu-meter and so on, but they also can do actions.

AmiStart calls defined functions to get informations about the Tool, how to initialize them and
how to send Messages to them.


How to start?

First think about what version of a Tool you really need, see the Version
Tool Description below. For example if you only need Version 39 Functions
set VERSION in the File LibInit.c to 39 (all tools must at least have
Version 39, coz this is the initial Version). Unsing a Version prevents AmiStart
from calling Functions of upper Versions, but all Functions must be implemented
for this Version and all of its parent.
Change the EXLIBNAME, REVISION and Copyright notice in LibInit.c.
Implement all Tool Functions for your specific Version in the File ModuleFuncs.c
Finally compile StartUp.c LibInit.c and ModuleFuncs.c link them in this order without
any StartUp Code (library linking) and finnaly link the amiga.lib, name the output
"toolname".tool, where toolname is the same name as defined in libInit.c named
EXLIBNAME.

The resulting tool could be copied to any location, preferring the "modules" directory in the AmiStart
directory, or in a directory "modules" inside the DATAPATH defined by the DATAPATH ToolType..

NOTE: i have only tested the vbcc makefile!

How a Tool Work.

A Tool doesn't have a specific data structure you will be free to implement your
data as you need it, all requests will be done by specific Functions with fixed
parameters and fixed results, this functions must be implement.

Further your Tool must implement a message port, after initializing the Tool AmiStart send messages
to the Tools Port, a Tool will get Space onto the TaskBar and can use it to display informations
as well as it can launch for Mouse/Timer events.

I recommend to use this example source to build your own Tool, a Tool consits of several
functions for initializing the tool, it must implement a MessagePort to communicate with
AmiStart and therefore it must be a own thread (task).

AmiStart initializes the tool in the following way:

 OpenTool()->NewTool()->GetToolWidth()->GetToolHeight()->GetToolPort()->InitTool()

 after NewTool() is called you have to create the Task and this Task must create the Message port and stop all
 activities. You will get a ASCLASS_START Message to activate your tool, to remove your Tool you will get a
 ASCLASS_STOP message (this only should stop your Tool not remove it, there are also other reasons to recive this
 message).

 The DisposeTool() method will be called to remove your Tool.

******************************************************************************************
******************************************************************************************


Which Functions must be implement?

Note: Newer Versions must implement previous Version Functions.
Note: a Tool is library based, so you must make all functions reentrant.

A Function has the following Structure:

    RETURNTYPE FunctionName(PAREMETER1, PARAMETER2, ...)

    while PARAMETERS are all filled by AmiStart,

******************************************************************************************

Version 39: (initial Version)

    BOOL OpenTool()

        Initial a Tool.

        INPUTS: none
        OUTPUT: BOOL, if FALSE initialization fails and the tool will not be used

        Description:
            AmiStart calls this command to initialize your tool-library, you can open libs and other resources, but
            you can launch a tool multiple, so make sure, coz tools are libraries, you will not open them multiple
            for example use global library variables initialize them by NULL and test it before. (See the example tool)

        See: CloseTool()

    VOID CloseTool()

        Opposit of OpenTool().

        INPUTS: none.
        OUTPUT: none.

        Description:
            Be sure to make this Function "call save", coz it will be called
            even if OpenTool() fails.
            Do some cleanup here for example closing libs you have opened in OpenTool().

        See: OpenTool()

    STRPTR ToolInfo()

        Get a short info string for this Tool.

        INPUTS: none
        OUTPUT: STRPTR a pointer to a Tool Info String.

        Description:
            AmiStart calls this function to get a (very) short (single line) Info Text.
            Use a constant string!!

    APTR NewTool(APTR prefs = REG(a0), APTR pool = REG(a1))

        create a new Tool.

        INPUTS: prefs   Pointer to optional prefs data saved in the AmiStart prefs file or NULL
                pool    A Pointer to an exec memory pool the tool could use to prevent memory fragmantation, you could
                        use AllocVec/AllocMen instead.
                        Memory flags are MEMF_ANY|MEMF_CLEAR, so you can be sure to get memory filled with zero bytes.
        OUTPUT: APTR    tool specific data, is passed to nearly all Tool functions by AmiStart, therefore you must return a
                        non NULL value!

        Description:
            Once AmiStart is loaded and a Tool is initialized by OpenTool(), AmiStart calls this Function, you have to
            initialize your default setup and create your task (for the Message handler)
            Return a pointer to a struct or something else, this Data will be used to get Infos about your tool it will be
            passed to DataRetieving functions.
            The prefs data will be passed from AmiStart, assume your tool has a prefs window and you like to save the prefs, there
            are several ways, a nice way is to save it within the AmiStart prefs file. Therefore AmiStart will call each time
            the user wants to save the configuration the two GetToolPrefs/Size functions and save this data within the prefs file.
            you will get a pointer to this data (you must create a copy of it), or NULL to use a default setup.
            see the demo source.

        See: DisposeTool(), GetToolPrefs(), GetToolPrefsSize()

    void DisposeTool(APTR tool = REG(a0))

        opposite of NewTool()

        INPUTS: tool    return value from NewTool()

        Descrption:
                cleanup all allocations done by InitTool(), also you must remove your task.
                Before you remove your task it have to delete the MessagePort.

        See: InitTool()

    UWORD ToolWidth(APTR tool = REG(a0), UWORD width = REG(d0))

        AmiStart calls this to find out your Tool width.

        INPUTS: tool    returnstatement from NewTool()
                width   AmiStart gives a suggestion, but you can use your preferred width
        OUTPUT: UWORD   width AmiStart will alloc for your tool.

        Description:
            AmiStart needs to know how many space your Tool need on the TaskBar this function will be called
            to figure out the Width, ToolHeight() will be called first!

        See: ToolHeight()

    UWORD ToolHeight(APTR tool = REG(a0), UWORD height = REG(d0))

        AmiStart calls this to find out your Tool height.

        INPUTS: tool    returnstatement from NewTool()
                height  AmiStart gives a suggestion, but you can use your preferred height
        OUTPUT: UWORD   height AmiStart will alloc for your tool.

        Description:
            AmiStart needs to know how many space your Tool needs on the TaskBar this function will be called
            to figure out the Height, it will be called before ToolWidth()!

        See: ToolWidth()

    ULONG GetToolFlags(APTR tool = REG(a0))

        Amistart calls this to find out your Tool Flags.

        INPUTS: tool    returnstatement from NewTool()
        OUTPUT: ULONG   Flags for your Tool.

        Description:
            You have to return your Tool Flags, possible flags are

            TOOLS_FLAG_FMOUSE   ,   your Tool will recieve Mouse Messages (if the pointer is over your Tool)
            TOOLS_FLAG_FTIMER   ,   your Tool will recieve Timer Messages (a very simple timer, you should use the timer-device instead)
            TOOLS_FLAG_NOSETUP  ,   set this Flag if your Tool does not have a setup window.

    struct MsgPort *GetToolPort(REG(a0) Tool *tool)

        Amistart calls this to find out yours Tool Message Port.

        INPUTS: tool    returnstatement from NewTool()
        OUTPUT: MsgPort pointer to your Tools MessagePort

        Description:
            AmiStart needs a Tools-Msg-Port to communicate with, use this to let AmiStart know where to find it.
            This Msg Port should be private, don't use AddPort to make it public


    UWORD GetToolBufferType(APTR tool = REG(a0))

        Return the Display Buffer Type of your tool

        INPUTS: tool    returnstatement form NewTool()
        OUTPUT: UWORD   type of the graphics Buffer for your Tool AmiStart has to alloc.

        Description:
            to Display any informations on the TaskBar you need access to the Display.
            AmiStart does not allow direct access to the Graphics resources instead of this
            you will get two equal Buffers, one for drawing and one for buffering, the buffering Buffer is
            filled with the TaskBar background (also the drawing buffer). You can copy the 2nd buffer into the
            drawing buffer to restore the TaskBar background.
            AmiStart supports two Buffer Types:

                TOOLS_TYPE_BITMAP   you will get a BitMap Buffer you can attach it to a rastport and
                                    use System functions for drawing into it.
                                    Note on True/HiColor Workbench screens you will get True/HiColor bitmaps!
                                    Use bltbitmap to copy the 2nd buffer to the first buffer for restoring the background.
                                    NOTE: This way is not well tested!!

                TOOL_TYPE_TRUECOLOR you will get two TrueColor buffers, each Pixel is represented by a ULONG (32Bit) in the
                                    ARGB Format (A=Alpha, R=RED, G=GREEN, B=BLUE), the buffer is width*height*4 Bytes large,
                                    use a loop or CopyMem to copy the 2nd to the 1st buffer to restore your Background.

    UWORD ToolSetup(APTR tool = REG(a0), UWORD mousex = REG(d0), UWORD mousey = REG(d1))

        AmiStart calls this to open your Tool Setup Window

        INPUTS: tool    returnstatement from NewTool()
                mousex  only if you want to open your window around the mouse
                mousey  ...
        OUTPUT: UWORD   in V39 zero should be returned.

        Description:
            This function will be called if the user will setup your tool.
            NOTE: only possible if you clear the TOOLS_FLAG_NOSETUP flag

        See: GetToolPrefs(), GetToolPrefsSize(), GetToolFlags()

    APTR GetToolPrefs(APTR tool = REG(a0))

        if you want to save your tool Prefs within the amistart-prefs file.

        INPUTS: tool    returnstatement form NewTool()
        OUTPUT: APTR    pointer pointing to your prefs or NULL.

        Description:
            if your Tool supports a setup window, you propably need to save this settings, you can use this
            to return a pointer to your prefs struct.
            The data will be requested and encoded by AmiStart while saving your prefs. It will be passed to
            your Tool while startup AmiStart (by NewTool()).

        See: NewTool(), ToolSetup(), GetToolPrefsSize()

    int GetToolPrefsSize(APTR tool = REG(a0))

        AmiStart calls this to recieve your prefs data size

        INPUTS: tool    returnstatement from InitModule()
        OUTPUT: int     lenght of your prefs buffer.

        Description:
            Before saving your tool prefs AmiStart needs the size of this data, return the length of it or ZERO.
            Note, coz the prefs are encoded and saved within the AmiStart setup-file your prefs should be very small
            (arround 200 Bytes)

        See: GetToolPrefs()

    void InitTool(APTR tool = REG(a0), APTR bm = REG(a1), APTR buffer = REG(a2), APTR hook = REG(a3), APTR t = REG(a4))

        AmiStart calls this to setup your display buffers.

        INPUTS: tool        returnstatement from NewTool()
                bm          pointer to your 1st display buffer
                buffer      pointer to your 2nd display buffer
                hook        a callback Hook you have to call to display your Tool
                t           a typeless pointer you have to pass to the hook as the Object
        OUTPUT: none

        Description:
            After loading, launching and setup your tool (you will recieve a STOP message before), this
            function will be called to pass pointers to the graphics buffers and the paint hook to your Tool.
            Buffers are from the Type of GetToolBufferType().
            This procedure could be called each time after a STOP Message!!!!
            the 1st Buffer is only to be used for restoring the Background, the 2nd will be used by the
            callback-hook to paint your Tool.

        See: GetToolBufferType()

*************************************************************************************

Version 40: (not yet defined)



*************************************************************************************

How to implement your MessagePort:

    Create a nonpublic Message-port via CreateMsgPort() and AmiStart will ask it's address via
    GetToolPort().

    AmiStart will send a asMessage each Time a Event occur.

    the asMessage.class member will get one of the following codes:

        ASCLASS_MOUSE   for mouse events, like mousemovements
        ASCLASS_TIMER   for timer events for timer events (very limited)
        ASCLASS_START   AmiStart requests your Tool to Start (see below)
        ASCLASS_STOP    AmiStart requests your Tool to Stop (see below)

        ASCLASS_MOUSE:  mousemove events, only created if you set the TOOLS_FLAG_FMOUSE flag in GetToolFlags()
                        in this case you will get the x, y coordinates and the qualifier mask in x, y and code.
        ASCLASS_TIMER:  you will get this Message in periodic loops (only if you set the TOOLS_FLAG_TIMER flag
                        in GetToolFlags(), this Timer stops in many cases (for example during Filesystem operations).
        ASCLASS_START:  this message only tells you that your Tool could manipulate the Graphics-Buffers (InitTool()), and
                        that you can call the paint-Hook. You can do other things without waiting for this Message.
                        You will always get this Message after InitTool(), but you can get it in any other Cases.
        ASCLASS_STOP:   if this Message is send, you must stop manipulating the image-buffers and to call the paint-Hook (
                        set by InitTool()).
                        This Message should only be replyed after you have stopped the access to this buffers, coz AmiStart
                        could remove this Buffers after this Message, also AmiStart could remove your Tool (via DisposeTool()).
                        You can also get a InitTool() call after this message to reinitialize your image-buffers.


Finally:
    post me a message, if something is unclear or you need help, or you have some suggestions.

    Darius Brewka
    [e-mail]